home *** CD-ROM | disk | FTP | other *** search
/ Linux Cubed Series 7: Sunsite / Linux Cubed Series 7 - Sunsite Vol 1.iso / system / news / readers / nn-tk.001 / nn-tk~ / nn / doc / INSTALLATION next >
Text File  |  1995-08-21  |  13KB  |  424 lines
  1.          CONFIGURATION AND INSTALLATION OF NN & NN-TK
  2.          --------------------------------------------
  3.  
  4.  
  5. This file describes the necessary steps to configure and install nn.
  6. You are advised to read this file before proceeding with the installation.
  7.  
  8. If you want to use NNTP (accessing news from a remote host), you must
  9. also read the file NNTP.
  10.  
  11. NN & NN-TK
  12. ----------
  13. It is a compile option (TK) as to whether NN (the character interface)
  14. or NN-TK (the X windows interface) is built.
  15.  
  16. To build NN-TK you need to have TCL and TK installed.
  17.  
  18. The following command line prompts are used in the examples:
  19.    `$' is used when no special privileges are required.
  20.    `#' is used when SUPER USER privileges may be required.
  21.  
  22.  
  23.                 STEP 1
  24.  
  25.           CREATE CONFIGURATION FILE config.h
  26.           ----------------------------------
  27.  
  28. The configuration file is distributed in the file config.h-dist.  You
  29. must COPY this to config.h before proceeding.  Keep the original -dist
  30. file to allow patches to be applied to it if necessary.
  31.  
  32.     $ cp config.h-dist config.h
  33.  
  34.  
  35.                 STEP 2
  36.  
  37.          EDIT config.h TO REFLECT YOUR SYSTEM
  38.          ------------------------------------
  39.  
  40. For each required configuration parameter, the config.h file contains
  41. verbose comments explaining the meaning of each parameter in the file.
  42. Read and follow these instructions carefully.  If you do that, nn
  43. should compile and run without problems.
  44.  
  45. Further information about the parameters can be found below in case
  46. you are in doubt.  Regarding the NNTP related definitions, consult the
  47. file named NNTP.
  48.  
  49. Notice that every time you edit config.h, the file update.h is
  50. modified to make a new configuration level for the version in the
  51. source directory.  The current configuration is showed in the version
  52. string as #number.
  53.  
  54. Finally, a single config.h can be used even if you maintain nn on
  55. several platforms.  Use predefined macro definitions to #ifdef the
  56. inclusion of configuration files and varying definitions.
  57.  
  58.  
  59.          STEP 2.1: CONFIGURATION OF MAKEFILE
  60.          -----------------------------------
  61.  
  62. Check the 'Makefile' file for the following parameters.  To ease
  63. future upgrades, override these values with definitions in config.h.
  64. The proper definition is provided in parenthesis.  For example, to use
  65. gcc as a compiler, add "#undef COMPILER" if necessary, and "#define
  66. COMPILER gcc" to config.h.
  67.  
  68. CC    The command to invoke the C compiler (COMPILER).
  69.  
  70. CPP    The command to invoke the C preprocessor with the result
  71.     written to the standard output stream (PREPROC).
  72.  
  73. CFLAGS    Flags to the C compiler (e.g. -O or -g) (CDEBUG for debug or
  74.     optimization flags, COMPILER_FLAGS for everything else).
  75.  
  76. LDFLAGS    Additional flags to the C compiler when linking executables
  77.     (LDEBUG, LOADER_FLAGS and EXTRA_LIB).
  78.  
  79. Notice that mandatory system specific definitions for the above are
  80. usually defined in the s- file (see below).
  81.  
  82.  
  83.        STEP 2.2: SPECIFY NETWORK AND NNTP CONFIGURATION
  84.        ------------------------------------------------
  85.  
  86. If you use nn on a single system with news on its local disks, you
  87. will not have to worry the least about networking, and you simply
  88. leave NNTP undefined.
  89.  
  90. Otherwise, consult the file NNTP for further instructions on sharing
  91. the news file and/or the database via NFS and/or NNTP.
  92.  
  93.  
  94.              STEP 2.3: SELECT SYSTEM FILE
  95.              ----------------------------
  96.  
  97. A list of systems that nn runs on and their associated include files
  98. is found in the file doc/MACHINES.
  99.  
  100. If none of these can be used on your system, create your own based on
  101. the file conf/s-template.h.
  102.  
  103.  
  104.             STEP 2.4: SELECT MACHINE FILE
  105.             -----------------------------
  106.  
  107. A list of machines that nn runs on and their associated include files
  108. is found in the file doc/MACHINES.
  109.  
  110. If none of these can be used on your system, create your own based on
  111. the file conf/m-template.h.
  112.  
  113.  
  114.             STEP 2.5: LOCALIZE NN
  115.             ---------------------
  116.  
  117. You will have to specify a number of files and directories which nn
  118. has to know about to work properly.  If you don't specify these, nn
  119. will in most cases use it own alternatives which will correspond to
  120. common practices on most installations.
  121.  
  122. The following directories and files can be defined in config.h:
  123.  
  124.  
  125. BIN_DIRECTORY        (mandatory)
  126.  
  127.     The directory where you want the user programs to be
  128.     installed.  The following programs will be installed in that
  129.     directory:
  130.  
  131.     nn        The news reader program
  132.     nn-tk        The X  windows news reader program
  133.  
  134.     nnacct        Accounting, quota, and access management
  135.     nncheck        Check for unread articles (link to nn)
  136.     nngrep        Grep for news groups (link to nn)
  137.     nnpost        Standalone posting program (link to nn).
  138.     nntidy        Cleans up the rc file (link to nn)
  139.  
  140.  
  141. LIB_DIRECTORY
  142.  
  143.     The directory where nn's auxiliary programs and files will
  144.     be installed unless another directory is specified by one of
  145.     the following definitions.
  146.  
  147.  
  148.  
  149. CLIENT_DIRECTORY    (optional, default = LIB_DIRECTORY)
  150.  
  151.     Contains the auxiliary programs and files required by the nn
  152.     program:
  153.  
  154.     aux    The shell script used in connection with replies etc.
  155.         It knows about common editors like vi and gnu emacs to
  156.         have them position the cursor appropriately.  To add
  157.         support for your own favourite editor, you should edit
  158.         the file aux.sh, not the compiled `aux' script!
  159.  
  160.  
  161.  
  162. HELP_DIRECTORY        (optional, default = CLIENT_DIRECTORY/help)
  163.  
  164.     The directory where the help files and online manual are
  165.     stored.  This directory is an obvious candidate for sharing in
  166.     a network.
  167.  
  168.  
  169. CACHE_DIRECTORY        (optional, default = each user's .nn directory)
  170.  
  171.     Only used with NNTP!! Directory to be used as a common storage
  172.     for temporary cache files when nn is used with NNTP.  Using a
  173.     common directory for cache files allows you to clean these out
  174.     on reboot with a single "rm" command in the rc file:
  175.          (cd CACHE_DIRECTORY; rm -f *)
  176.     But of course this requires that you use a separate directory
  177.     for the cache!
  178.  
  179.  
  180. TMP_DIRECTORY        (optional, default = /usr/tmp)
  181.  
  182.     The directory to be used as temporary storage for files used
  183.     when editing responses etc.
  184.  
  185.  
  186. NEWS_DIRECTORY        (optional, default = /usr/spool/news)
  187.  
  188.     The directory containing the news spool directories and files.
  189.     It is not required when a remote NNTP server is used.
  190.  
  191.  
  192. NEWS_LIB_DIRECTORY    (optional, default = /usr/lib/news)
  193.  
  194.     The directory containing the news system's active file and
  195.     other related files.
  196.  
  197.     When a remote NNTP server is used, it is still needed as the
  198.     location of the (mini-)inews program if posting is allowed
  199.     (unless INEWS is explicitly defined to override the default
  200.     location).
  201.  
  202.  
  203. LOG_FILE    (optional, default = LIB_DIRECTORY/Log)
  204.  
  205.     The log file used by nnmaster and nn to store reports, error
  206.     messages, usage statistics, etc.
  207.  
  208. TKINCLUDE    (default /usr/local/tcl/include)
  209.     The location of the TCL/TK include files
  210.  
  211. TKLIB        (default /usr/local/tcl/lib)
  212.     The location of the TCL and TK libraries for linking
  213.     into NN-TK
  214.  
  215.                 STEP 3
  216.  
  217.              COMPILE THE SOFTWARE
  218.              --------------------
  219.  
  220. To compile the software, you just have to run one of the following
  221. make commands.
  222.  
  223. If you are making a complete package with both master and client, do
  224.  
  225.     $ make all
  226.  
  227. If you want to share a database which resides on another host (through
  228. NFS/RFS/rdist), you don't need a master on the local system, so you
  229. can do the following instead:
  230.  
  231.     $ make client
  232.  
  233.  
  234.                 STEP 4
  235.  
  236.                INSTALLING THE SOFTWARE
  237.                -----------------------
  238.  
  239. Installation of the nn software is handled entirely via a script
  240. "./inst" created during the compilation.  The components of nn are
  241. split into five parts, which can be installed separately or in various
  242. combinations depending on whether you run a stand-alone system or
  243. networked systems sharing the database and other parts of the nn
  244. package.  The five components are:
  245.  
  246. 1) User files and programs (machince dependent, shareable)
  247.    Install the BIN_DIRECTORY programs.
  248.  
  249. 2) Auxiliary programs (configuration dependent, shareable)
  250.    Install the CLIENT_DIRECTORY files and programs, this includes
  251.    the tcl directory when NN-TK keeps its tcl files.
  252.  
  253. 3) Documentation (shareable)
  254.    Install the MAN pages in the proper directories.
  255.  
  256. 4) Help files (shareable)
  257.    Install the HELP_DIRECTORY files (except online manual).
  258.  
  259. 5) Online manual (shareable with 5)
  260.    Format and install the online manual in HELP_DIRECTORY.
  261.  
  262. 6) The nn-tk binary
  263.    Install in BIN_DIRECTOR
  264.  
  265. Unless you have defined yourself as the owner of the nn package and
  266. have write permission on all the necessary directories, you will need
  267. to be super-user to install nn, so start with
  268.  
  269.     $ su
  270.  
  271. Now run the installation script:
  272.  
  273.     # ./inst
  274.  
  275. The `inst' script will list a menu with the following choices:
  276.  
  277. (1)-(6)    Install individual parts of the package.
  278.  
  279. (s)    Install a complete server + client package (1-6).
  280.  
  281. (c)    NN (character version) full installation (excluding nnmaster)
  282.  
  283. (t)    NN-TK full installation (excluding nnmaster)
  284.  
  285. (h)    Install a client with local auxiliary files, but shared
  286.     documentation and help files (2-3).
  287.  
  288. (n)    Install a client accessing only the database via a network (2-6).
  289.  
  290. (m)    Install only the nnmaster (1).
  291.  
  292. (c)    Install only the client programs (2).
  293.  
  294. (u)    Update already installed parts of the package.  This will
  295.     check for the existence of the old programs, and only update
  296.     programs and files already installed.  You will typically use
  297.     this after applying patches.
  298.  
  299. You can also run the `inst' script with the choices as arguments, e.g.
  300.  
  301.     ./inst m c
  302.  
  303. TCL
  304. ---
  305. The tcl files the implement the X interface in NN-TK are installed
  306. in the tcl directory in the CLIENT_DIRECTORY, usuall /usr/local/lib/nn/tcl.
  307. NN-TK will will look for the tcl directory in the current directory and
  308. the in .nn before looking in /usr/local/lib/nn/tcl so it is possible to
  309. replace the system wide tcl files with a local copy.
  310.  
  311. EXMH
  312. ----
  313. Using EXMH adds a significant extra capabilities to NN-TK.
  314.  
  315. To include the EXMH routines create a symbolic link named exmh
  316. in the tcl directory pointing to the EXMH lib directory. It
  317. isn't necessary to have MH installed. If EXMH is not available
  318. NN will still work, but will less functionality.
  319.  
  320.  
  321.  
  322.                 STEP 7
  323.  
  324.             INSTALL AND EDIT GLOBAL FILES
  325.             -----------------------------
  326.  
  327. Depending on your needs, you should create the following files on each
  328. host running nn (you may also just share the files if you like):
  329.  
  330. CLIENT_DIRECTORY/init
  331.     The global init file for all users on the system.  Users will
  332.     be able to override the definitions in this file, but you can
  333.     probably make some sensible decisions which will prevent
  334.     novice users from getting into trouble, for example set the
  335.     default distribution to "local" etc.
  336.  
  337.     You can also specify a global presentation sequence here.
  338.  
  339.     You may use init.sample as a starting point, but don't use it
  340.     without careful examination.  Especially, the sequence part
  341.     is mainly an illustration of the possibilities.  If you are in
  342.     doubt, just delete the sequence part of the file (groups will
  343.     then be presented in pure alphabetical order).
  344.  
  345. CLIENT_DIRECTORY/routes
  346.     You DO NOT NEED this file if you already run a domain based
  347.     mailer, i.e. when HAVE_ROUTING is defined in config.h.
  348.  
  349.     Otherwise, you can use it as a configuration file for the
  350.     domain address remapping done by nn in reply addresses and the
  351.     nnmail program.  You may use routes.sample as a starting point
  352.     (it briefly describes how to build a routes file).
  353.  
  354.     Please notice that neither the routes functionality, nor
  355.     nnmail is a supported part of nn - if you really want to
  356.     run a domain-based mailer, get smail 2.5 or later.  And if you
  357.     ask me how to use it I will answer: "Get SMAIL instead".
  358.  
  359. CLIENT_DIRECTORY/motd
  360.     Every time you change this file, it will be shown to the nn
  361.     users the next time they invoke nn.  This can be used to
  362.     inform the users about changes in the news environment or
  363.     local policies.  (motd = message of the day)
  364.  
  365.  
  366. NNTP_SERVER
  367.     Must contain the host name of the NNTP-server when NNTP is
  368.     used.  If you already run NNTP with your other news readers,
  369.     this file does not need to be modified.
  370.  
  371. CLIENT_DIRECTORY/nn-defaults
  372.     This file is in X resource format, it contains the defaults 
  373.     for the various NN-TK options. It also contains resources
  374.     setting other aspects of the interface such as colors, fonts
  375.     and adjustments to the EXMH interface. The resources can also
  376.     be set in the X server.
  377.  
  378.     The system wide nn-defaults can be overridden by having a
  379.     local file in .nn
  380.  
  381.  
  382.                 STEP 8
  383.  
  384.                TEST THE BASIC FUNCTIONS
  385.                ------------------------
  386.  
  387. If any of the following tests fails or you see other peculiar
  388. behaviour, you should consult the PROBLEMS file.  You may not be the
  389. only one to have seen the problems, and there might even be a solution.
  390.  
  391. There are a few things you should check to ensure the proper
  392. functioning of nn.
  393.  
  394. 1) Backup your current .newsrc file if you have one.  (Don't save it
  395.    in .newsrc.bak or .newsrc.orig since nn may use these names).
  396.  
  397. 2) Run `nn'.  
  398.  
  399. 3) Does nn find any news?  If not, does nn -x find anything?
  400.  
  401. 4) Can you send mail to yourself?  Try the sequence:
  402.     m (return) (return) testing (return)
  403.     edit the letter
  404.     s (return)
  405.  
  406.    If not, you should check the REC_MAIL program.
  407.  
  408. 5) Can you post an article to the local test group?  Try:
  409.     :post (return)
  410.        test (return)
  411.        local (return)
  412.     edit the article
  413.     s (return)
  414.  
  415.    If not, you should check the INEWS program.
  416.  
  417.  
  418.          -------------------------------------------
  419.              IF EVERYTHING WORKS
  420.          YOU HAVE COMPLETED THE INSTALLATION
  421.          -------------------------------------------
  422.  
  423.  
  424.